API de Hierarquia - Documentação Completa

📋 Visão Geral

A API de Hierarquia é responsável por fornecer consultas estruturadas e navegação hierárquica no sistema CordenaAi, implementando a estrutura organizacional completa: Instituições → Unidades → Turmas → Horários → Alunos. Esta API permite navegação eficiente através dos níveis hierárquicos, facilitando a construção de interfaces administrativas, relatórios organizacionais e gestão de estrutura educacional.

🎯 Endpoints Disponíveis

🆕 Novos Endpoints - Consultas Específicas

1. GET /api/hierarquia/horario-completo/{horarioId}

Obter Horário Completo com Hierarquia

2. GET /api/hierarquia/horarios-usuario/{identificacao}

Obter Horários por Usuário

3. GET /api/hierarquia/debug-horarios

Debug: Listar Todos os Horários

🏗️ Endpoints Existentes - Navegação Hierárquica

4. GET /api/hierarquia/instituicoes

Obter Todas as Instituições

5. GET /api/hierarquia/unidades/{idInstituicao}

Obter Unidades por Instituição

6. GET /api/hierarquia/turmas/{idUnidade}

Obter Turmas por Unidade

7. GET /api/hierarquia/horarios/{idTurma}

Obter Horários por Turma

8. GET /api/hierarquia/turma/{idTurma}/alunos

Obter Alunos por Turma

9. GET /api/hierarquia/instituicao/{idInstituicao}/completa

Obter Hierarquia Completa da Instituição

10. GET /api/hierarquia/buscar-usuarios

Buscar Usuários na Hierarquia

11. GET /api/hierarquia/destinatarios

Obter Contadores de Destinatários

🔧 Modelo de Dados

Estrutura de Instituição

{
  "id": "integer",
  "nome": "string",
  "local": "string",
  "tipo": "TipoInstituicao",
  "unidadesCount": "integer"
}

Estrutura de Unidade

{
  "id": "integer",
  "nome": "string",
  "local": "string",
  "tipo": "TipoUnidade",
  "instituicaoNome": "string",
  "turmasCount": "integer"
}

Estrutura de Turma

{
  "id": "integer",
  "nome": "string",
  "status": "StatusTurma",
  "unidadeNome": "string",
  "responsavelNome": "string",
  "alunosCount": "integer"
}

Estrutura de Horário

{
  "id": "integer",
  "turmaId": "integer",
  "turmaNome": "string",
  "descHorario": "string",
  "usuarios": [
    {
      "id": "integer",
      "usuarioId": "string",
      "usuarioNome": "string",
      "papelId": "integer",
      "papelNome": "string"
    }
  ]
}

Estrutura de Aluno

{
  "turmaNome": "string",
  "usuarioNome": "string",
  "usuarioId": "string",
  "papelNome": "string",
  "horarioDescricao": "string"
}

Estrutura de Hierarquia Completa

{
  "id": "integer",
  "nome": "string",
  "local": "string",
  "tipo": "TipoInstituicao",
  "unidades": [
    {
      "id": "integer",
      "nome": "string",
      "local": "string",
      "tipo": "TipoUnidade",
      "turmas": [
        {
          "id": "integer",
          "nome": "string",
          "status": "StatusTurma",
          "alunos": [
            {
              "usuarioId": "string",
              "usuarioNome": "string",
              "papelNaTurma": "PapelNaTurma"
            }
          ]
        }
      ]
    }
  ]
}

Estrutura de Usuário na Hierarquia

{
  "usuarioId": "string",
  "usuarioNome": "string",
  "usuarioCelular": "string",
  "papelNaTurma": "PapelNaTurma",
  "turmaNome": "string",
  "unidadeNome": "string",
  "instituicaoNome": "string"
}

Estrutura de Destinatários

{
  "instituicoes": "integer",
  "unidades": "integer",
  "turmas": "integer",
  "usuarios": "integer",
  "cadastros": "integer",
  "horarios": "integer"
}

🔐 Autenticação e Autorização

Todos os endpoints requerem:

📊 Casos de Uso Principais

1. Consulta de Horário Completo

GET /api/hierarquia/horario-completo/123
Authorization: Bearer {token}

2. Horários por Usuário

GET /api/hierarquia/horarios-usuario/usuario@email.com
Authorization: Bearer {token}

3. Debug de Horários

GET /api/hierarquia/debug-horarios
Authorization: Bearer {token}

4. Navegação Hierárquica Completa

GET /api/hierarquia/instituicoes
Authorization: Bearer {token}

5. Exploração por Níveis

GET /api/hierarquia/unidades/1
Authorization: Bearer {token}

6. Visualização de Turma

GET /api/hierarquia/turmas/5
Authorization: Bearer {token}

7. Consulta de Horários

GET /api/hierarquia/horarios/10
Authorization: Bearer {token}

8. Listagem de Alunos

GET /api/hierarquia/turma/10/alunos
Authorization: Bearer {token}

9. Estrutura Completa

GET /api/hierarquia/instituicao/1/completa
Authorization: Bearer {token}

10. Busca Avançada

GET /api/hierarquia/buscar-usuarios?instituicaoId=1&papel=Aluno
Authorization: Bearer {token}

11. Relatório de Destinatários

GET /api/hierarquia/destinatarios
Authorization: Bearer {token}

⚠️ Validações e Regras de Negócio

Validações Obrigatórias

Regras de Negócio

🚨 Tratamento de Erros

Códigos de Status HTTP

Formato de Erro

{
  "error": "string",
  "message": "string",
  "details": "string",
  "timestamp": "datetime"
}

📈 Performance e Limitações

Limitações

Otimizações

🔄 Integração com Outros Módulos

Módulos Relacionados

📱 Uso em Aplicações

Web App

Mobile App

🛠️ Manutenção e Monitoramento

Logs Importantes

Métricas Monitoradas

📚 Exemplos Práticos

Fluxo de Consulta Específica

  1. GET /api/hierarquia/debug-horarios para identificar IDs disponíveis
  2. GET /api/hierarquia/horario-completo/{id} para dados completos do horário
  3. GET /api/hierarquia/horarios-usuario/{identificacao} para horários do usuário

Fluxo de Navegação Hierárquica

  1. GET /api/hierarquia/instituicoes para listar instituições
  2. GET /api/hierarquia/unidades/{id} para unidades da instituição
  3. GET /api/hierarquia/turmas/{id} para turmas da unidade
  4. GET /api/hierarquia/horarios/{id} para horários da turma

Fluxo de Busca Avançada

  1. GET /api/hierarquia/buscar-usuarios com filtros específicos
  2. Aplicação de filtros hierárquicos no backend
  3. Retorno de usuários filtrados com contexto hierárquico
  4. Exibição de resultados com informações completas

Fluxo de Relatório Completo

  1. GET /api/hierarquia/instituicao/{id}/completa para estrutura completa
  2. Processamento de dados hierárquicos
  3. Geração de relatório organizacional
  4. Exportação de dados estruturados

🎯 Tipos e Enums

TipoInstituicao

TipoUnidade

StatusTurma

PapelNaTurma

Versão: 1.0
Última Atualização: Outubro de 2025
Status: ✅ Implementado e Testado
Base URL: /api/hierarquia
Responsável: Equipe de Desenvolvimento CordenaAi